home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Night Owl 6
/
Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso
/
037a
/
pavt110.zip
/
PAVATAR1.DOC
< prev
next >
Wrap
Text File
|
1991-09-07
|
20KB
|
478 lines
PAvatar 1.10
Preliminary Release
Turbo Pascal Avatar Level 1 Console Kit
Copyright 1991 Gregory P. Smith
Part I. Introduction
──────────────────────────────────────────────────────────────
This toolkit represents hundreds of hours of programming
that resulted in this fast and accurate product. PAvatar is a
Turbo Pascal unit (version 5.5 or later) that can provide your
programs with Avatar level 1 console, extended Avatar level 0+
(optional ANSI fallback), ANSI-BBS, and ANSI terminal
emulations. This is done with a series of procedural hooks
for screen I/O and cursor control. This allows you to use the
procedures of your choice, making the unit the most flexible
of its type.
An added bonus to using this unit is DESQview awareness.
This unit contains facilities for detecting DESQview, giving
up the time slice, and using DESQview's video buffer. This is
especially valuable for communications and bbs type programs
that are often run under DESQview.
Requirements
─────────────────────────────
This unit requires that you are using an IBM compatible
computer and have Turbo Pascal 5.5 or later. As I have used
OOP for fast and efficient data management within this unit; I
regret that I cannot provide a Turbo Pascal 5.0 version of the
PAvt1 unit.
Memory requirements within a program using PAvatar have
been kept to a minimum. Only 3-4k of heap space as well as
less than 500 bytes stack space. The actual code itself only
requires 16k.
Shareware
─────────────────────────────
I am distributing this unit under a relaxed shareware
concept so as to promote Avatar. You are free to use the
compiled unit however you want, as long as I'm given credit
for the terminal emulations somewhere in the documentation or
in the program itself. Please let me know of any programs
that you write using PAvatar so that I can recommend them to
others.
If you want the source code to this unit it is available
for $10 U.S., see the registration form for details. The
possible benefits of having source code are described later in
this document.
Liability
─────────────────────────────
To use PAvatar you must first agree that I cannot be held
responsible for any damages or problems that occur from its
use or misuse. If you do not agree to these terms don't use
this unit.
Part II. QUICK START
──────────────────────────────────────────────────────────────
First off you must install your unit. To do so, copy the
appropriate TPU file into your units directory (the TPU's have
been renamed to .T55 for TP 5.5 and .T60 for TP 6.0, you must
rename yours). Next, copy the demo program A1DEMO.PAS into
your pascal directory. Type TPC a1demo or compile it to disk
from the IDE. You now have a utility for displaying AVT/1,
AVT/0+, and ANSI files that is DESQview aware. Unless you're
a Sysop, you probably don't have lots of .AVT Avatar files.
Currently there is no Avatar editor, but you may use my ANSI
to Avatar/0+ converter to create Avatar files. It's found on
BBS's as A2AVTnnn.ZIP where nnn is the version number
(currently 2.10). When typing level 0 files, be sure to use
the /PLUS parameter to indicate that it is not a level 1 file
(The differences are described later).
Part III. Interface
──────────────────────────────────────────────────────────────
Procedures
─────────────────────────────
PAvatar is a self sufficient unit in that only two
procedures are required to add an Avatar or ANSI terminal to
your program. However, there are more than two procedures
available so that you can take advantage of many special
features of the unit. The procedures and definitions follow.
Procedure Parse_AVT1 (ch:char);
This is the main procedure of the unit. It takes
character ch and parses it according to the status. For
instance if you pass it a ^V it would go into the Avatar
command mode in which the next character would represent
an Avatar command. If it were an Esc and ANSI was
enabled, the next character passed to it would be tested
for a bracket '[' or a shorter VT52 style ANSI commands.
This is the heart of the whole unit.
Procedure ResetTerminal (nc,nl:byte);
This procedure is used to Reset the Terminal
emulation with screen dimensions nc columns and nl lines.
It always takes you back to the original mode with AVT/1
active, and ANSI fallback turned off. It has the same
effect as issuing a ^V^R to the AVT/1 parser.
Procedure SetScreen(nc,nl:byte);
Use this procedure when you want to change the size
of the terminal screen without resetting everything else
as in the ResetTerminal procedure. The only thing this
does is re-define all of the Avatar windows to have nc
columns and nl lines.
Procedure AvtInterp (ch:char);
This procedure is called by the Parser to interpret
the Avatar codes after DLE's and special considerations
have been processed. When in ANSI_Only or AVT/0+ mode
you can use this instead of Parse_AVT1. The extra
overhead of Parse_AVT1 is so small that using this is
usually not worth it.
Procedure AvtTTY (ch:char);
This procedure is called by the AVT/1 Parser when a
character is not part of a control code. It simply
writes character ch to the screen following the current
Avatar window setup (including flow, insert, direction,
etc..). The only characters that it processes are CR,
LF, BS, Tab, and Bell. You should not need this
procedure, but it's here if you do.
Procedure Level0_Simulation (fallbck:boolean);
This procedure places the interpreter into an
extended AVT/0+ emulation mode. If fallbck is true ANSI
fallback will be on. Internally, this procedure re-
configures AVT/1's window 0 to have a default color of
cyan (3), as well as turning cooked mode off. Using this
procedure is more effective than sending the equivalent
codes for defining a level 0 simulation in a certain
window. Destructive backspaces are also disabled.
Procedure ANSI_Only;
Use this procedure when you want to place the
parser in ANSI Only mode. It is the equivalent of
putting the AVT/1 parser to sleep and disabling fallback.
This is faster than fallback mode.
Procedure AvtSound (note:byte; oct:shortint; dur:byte);
This procedure is a shortcut to stuff music into
the Avatar sound buffer without having to send the code
to the parser. Note represents the musical note in the
same method which AVT/1's ^V^S command uses it. That is
note is equal to (tone - 'A') * 2 + sharp where tone is
somewhere between 'A' and 'G'. Sharp is a 0 or a 1 as
the case may be. A pause is generated by a note of 14 or
greater. The octave is a signed integer in oct where 0
represents middle octave and 1 the next highest, -1 the
next lowest. Dur is the duration in tenths of a second.
If two identical notes are queued in a row, they will be
played legato so that they run together.
Procedure StuffSound (frq,dur:integer);
This procedure is called by the above procedure.
It is used to place a sound of frq hertz and dur tenths
of a second into the Sound buffer. If the buffer is
full, it will wait until space is available.
Function DESQview_version: word;
This is the first of the DESQview supportive
routines in this unit. The DESQview major version number
is in the high byte, while the minor version is in the
low byte. A zero is returned if DESQview is not loaded.
Procedure DV_Pause;
This procedure will give up the current time slice
if you are in DESQview. It does nothing otherwise. Use
this procedure when your program is not doing anything,
to give the other programs more processing time. Do not
hesitate to use this procedure, it's written in assembler
so that it's execution time isn't even measurable.
Function ReadKey: char;
This is a replacement for the Crt unit's ReadKey
that gives up the current DESQview time slice (via
DV_Pause) if a key hasn't been pressed.
Procedure SwapVectors;
If you plan on shelling to DOS or swapping portions
of your program out, this is a must. As Avatar uses
background sound, the unit hooks into interrupt $1C.
This is an extension of the DOS unit's SwapVectors which
also restores interrupt $1C.
Variables
─────────────────────────────
There are only a few non-procedural variables that you can
use to check or modify the status of the terminal. They are
all static variables with defined defaults.
ANSI_BBS : boolean = False;
Use this variable to decide whether the ANSI
portion of the unit will use the "BBS" style. The only
differences when this is true are that Esc[2J also homes
the cursor and Esc[J acts the same as Esc[2J instead of
Esc[0J. DOS's own ANSI.SYS is infamous for processing
Esc[2J this way.
Fallback : boolean = False;
This variable controls whether ANSI fallback will
be on during Avatar emulations. It is best not to mess
with this variable when using AVT/1 as it is designed
primarily for use with AVT/0+.
ScrnLines : byte = 25;
This variable simply defines the number of lines
that you want on your terminal screen. Modifying this
variable can produce strange results. It is recommended
that you use the Terminal Reset procedure to define the
screen size.
ScrnColumns : byte = 80;
This variable is the partner of the above one. It
defines the number of columns you want on your terminal
screen. The same restrictions apply with this variable
as on the above.
QueryReply : string[80] = 'AVT1, Avatar/1 Console Copr. 1991 Greg Smith. Ver 1.10'+^M;
When the Avatar terminal id request is received
this is the string that will be returned. The "AVT1," at
the beginning is important to the remote terminal. It is
used to define the capabilities of the terminal.
Everything else is just your own logo or program ID. In
level 0+ simulation mode the AVT1 is changed to AVT0.
Dest_BS : boolean = True;
As the name implies, this variable controls the
behavior of the backspace (^H) character. The AVT/1
specifications require a Destructive backspace while the
AVT/0 specifications require that it is non-destructive.
Constants
.
The following constants are available for general use.
Esc = ^[;
DLE = ^P;
FS = #28;
GS = #29;
RS = #30;
US = #31;
SP = #32; { space }
User Hooks
─────────────────────────────
The interface for this unit has been designed to be as
flexible as possible without hindering the performance of the
unit. Besides the main procedures and a few variables most of
it is procedural hooks. Their definitions follow.
Query_Hook : ReplyProc = Procedure (S:String);
This hook is used for all terminal queries or
responses such as the Avatar driver query and the ANSI
report cursor position. Usually these replies will be
placed in the keyboard buffer or sent out the comm port.
In a1demo, the hook is left at its null procedure setting
as there is no use for it in that type of utility. Note
that information passed to this hook should be inserted
immediately into the input or output buffer so that it is
the next thing to be processed if you wish to comply
fully with the AVT/1 specifications.
WriteATh : WriteATHookT = Procedure (x,y,a:byte;ch:char);
This hook is simple and important. It should write
character ch on the screen at location x,y using
attribute a. This is the only thing it should do, it
should not mess with the cursor or scroll the screen.
GotoXYh : GotoXYHookT = Procedure (x,y:byte);
This hook is used to set the cursor position.
Often this routine will call the Crt unit's GotoXY
procedure. It is provided for flexibility and the
possibility of using PAvatar in a virtual screen or
window. Full checking against ScrnLines and ScrnColumns
is performed internally.
Scrollh : ScrollHookT = Procedure (dir,x1,y1,x2,y2,n,a:byte);
This hook is important to Avatar's power. It
scrolls the screen region of (x1,y1)-(x2,y2) n lines in
the direction indicated in dir (1=up, 2=down, 3=left,
4=right). The empty area created by the scroll should be
filled with blank spaces of color attribute a. Most
decent windowing toolkits have a procedure suitable for
this.
FillAreah : FillHookT = Procedure (x1,y1,x2,y2,a:byte;ch:char);
This hook is used to fill the screen region of
(x1,y1)- (x2,y2) with character ch in attribute a. If
your scrolling procedure doesn't support a fill color for
the newly exposed area, this is a good procedure to use
for it.
GetATh : GetCharHookT = Procedure (x,y:byte;var a:byte;var c:char);
This hook is the opposite of the WriteATh hook in
that its purpose it to retrieve information from the
screen. Variable parameters c and a should be set to the
character and attribute at the coordinates of x,y
respectively.
HighAreah : HighHookT = Procedure (x1,y1,x2,y2,a:byte);
Similar to FillAreah, this hook fills an area of
the screen. The area defined by (x1,y1)-(x2,y2) should
be filled with attribute a, but the characters on the
screen should not be disturbed.
Pauseh : PauseHookT = Procedure (tenths:word);
The only purpose of this hook is to allow for
controlled system pauses. This hook should pause the
terminal for tenths tenths of a second. The reason I
didn't just use a delay(100) within the unit is for the
protection of the user. With avatar, codes could be sent
that could conceivable pause the system for several days.
It is up to you to add a method of breaking out of a
pause such as a key press.
FlushInputh : Procedure;
This hook has a default effect of zeroing the
keyboard buffer. If your program has any internal
buffers or communications buffer, you may wish to flush
them when this hook is called. The Avatar flush input
command calls this hook.
The PAvt0 Small Version
─────────────────────────────
Now included with the Pavt package is a PAvt0 Small version
of the unit. This unit is an AVT/0+ and ANSI-BBS terminal
only. It is much faster that the AVT/1 unit as there are no
flow and window controls. The primary use for this unit is
for BBS door programs which won't be using AVT/1. Overall the
code there is 10.5k less code and 650 bytes less data as well
as a minimal heap usage.
The PAvt0 unit is designed as a drop in replacement for the
PAvt1 unit. However there are a few procedures and variables
which don't exist in the PAvt0 unit. The Pauseh and
FlushInputh hooks are not available, the Level0_Simulation and
Parse_AVT1 procedures are not available (AvtInterp should be
used instead), and the ANSI_BBS variable is gone. All of
these were removed as they served no purpose in AVT/0+. In
addition, this unit parses tab characters (^I) as 8 spaces
instead of the definable (defaults to 8 char tabs) tab stops
of the full unit.
Part IV. Special Considerations
──────────────────────────────────────────────────────────────
Avatar 1 Console
─────────────────────────────
The Avatar level one console is a very powerful terminal
emulation. Naturally it goes without saying that there are a
few things that must be considered if you wish to comply with
the full AVT/1 console specifications. I've already mentioned
the need to insert the query replies first into the input or
output buffer. Secondly, AVT/1 features a sleep mode for its
interpreter, so ANSI fallback should not be used as a remote
program using level 1 codes should know how to switch between
sleeping (ANSI) and awake (AVT/1).
The main thing you should be concerned about in
communications is flow control. AVT/1 has a way to get around
interference with XON/XOFF flow control if the parser is in
cooked mode, but if it's switched to raw mode, the results
will be disastrous. As AVT/0+ is a raw only terminal,
XON/XOFF must be disabled while it is active.
Tips & Tricks
─────────────────────────────
The AvtInterp procedure is actually a procedural variable
that is passed a character as its only parameter. This should
let you know a lot about how PAvatar works internally, as well
as add flexibility. If you wish to add your own terminal,
just assign your own procedures to AvtInterp. This will work
when you are calling AvtInterp directly instead of Parse_AVT1.
Of course, remember to call the parser when you switch to
AVT/1.
That is the only "hidden" feature I will expose right now,
but expect more in upcoming versions.
Part V. History And Credits
──────────────────────────────────────────────────────────────
I thank Ping Hansen in the FidoNet pascal echo and an
unknown someone in the FidoNet communications echo for
sparking my interest in terminal emulations and Avatar. I
also would like to thank G. Adam Stanislav for taking on the
project of updating the Avatar specification past its original
Opus level commands. Last but not least, I would like to
thank my parents for putting up with me being on the computer
so many hours.
Release Sites
─────────────────────────────
The following is a list of BBS's where you can find the
latest version of PAvatar as well as contacting me.
(303)320-4078 CMOS BBS line 1, 300-9600, Fido: 1:104/441
(303)322-4125 CMOS BBS line 2, 300-9600, Fido: 1:104/469
(303)449-8946 Bohemia BBS Sys, 300-2400, Fido: 1:104/120
(303)750-7136 Borealis WildCat, 1200-9600, RIME: ->BOREALIS
(303)674-1305 Wizardry line 1, 1200-9600. Fido: 1:104/630
Mark Cook, Sysop of Wizardry, is my only beta tester at this time. I will acquire more as I feel the need.
──────────────────────────────────────────────────────────────
Send all questions, comments, problems, ideas, money, etc.. to:
Gregory P. Smith
4422 Pali Way
Boulder, CO. 80301 USA
Fidonet: 1:104/441,120,477,630
RIME: ->BOREALIS
UseNet/InterNet: gpsmith@bohemia.metronet.org
CompuServe: Route to above internet address.